Inside Macintosh: QuickTime /

Chapter 3 - Image Compression Manager / Image Compression Manager Reference

Image Compression Manager Functions / Working With Sequences

DecompressSequenceFrame

Your application calls the DecompressSequenceFrame function to decompress one of a sequence of frames. You must have called the DecompressSequenceBegin function before calling this function. You specify the destination with the port parameter to the DecompressSequenceBegin function, described in the previous section.

pascal OSErr DecompressSequenceFrame (ImageSequence seqID, 
               Ptr data, CodecFlags inFlags,
               CodecFlags *outFlags,
               CompletionProcRecordPtr asyncCompletionProc);

seqID

Contains the unique sequence identifier that was returned by the DecompressSequenceBegin function (described on page 3-107).

data

Points to the compressed image data. This pointer must contain a 32-bit clean address. If you use a dereferenced, locked handle, you must call the Memory Manager's StripAddress routine before you use that pointer with this parameter.

inFlags

Contains flags providing further control information. See "Image Compression Manager Function Control Flags," which begins on page 3-58, for information about CodecFlags fields. The following flags are available for this function:

codecFlagNoScreenUpdate

Controls whether the decompressor updates the screen image. If you set this flag to 1, the decompressor does not write the current frame to the screen, but does write the frame to its offscreen image buffer (if one was allocated). If you set this flag to 0, the decompressor writes the frame to the screen.

codecFlagDontOffscreen

Controls whether the decompressor uses the offscreen buffer during sequence decompression. This flag is only used with sequences that have been temporally compressed. If this flag is set to 1, the decompressor does not use the offscreen buffer during decompression. Instead, the decompressor returns an error. This allows your application to refill the offscreen buffer. If this flag is set
to 0, the decompressor uses the offscreen buffer if appropriate.

codecFlagOnlyScreenUpdate

Controls whether the decompressor decompresses the current frame. If you set this flag to 1, the decompressor writes the contents of its offscreen image buffer to the screen, but does decompress the current frame. If you set this flag to 0, the decompressor decompresses the current frame and writes it to the screen. You can set this flag to 1 only if you have allocated an offscreen image buffer for use by the decompressor.

outFlags

Contains a pointer to status flags. The decompressor updates these flags at the end of the decompression operation. See "Image Compression Manager Function Control Flags," which begins on page 3-58, for information about CodecFlags constants. The following flags may be set by this function:

codecFlagUsedNewImageBuffer

Indicates to your application that the decompressor used the offscreen image buffer for the first time when it processed this frame. If this flag is set to 1, the decompressor used the image buffer for this frame and this is the first time the decompressor used the image buffer in this sequence.

codecFlagUsedImageBuffer

Indicates whether the decompressor used the offscreen image buffer. If the decompressor used the image buffer during the decompress operation, it sets this flag to 1. Otherwise, it sets this flag to 0.

codecFlagDontUseNewImageBuffer

Forces an error to be returned when a new image buffer would have to be allocated instead of allocating the new buffer.

codecFlagInterlaceUpdate

Updates the screen by interlacing even and odd scan lines to reduce tearing artifacts (if the decompressor supports this mode).

asyncCompletionProc

Points to a completion function structure. The compressor calls your completion function when an asynchronous decompression operation
is complete. You can cause the decompression to be performed asynchronously by specifying a completion function. See "Completion Functions," which begins on page 3-148, for more information about completion functions.

If you specify asynchronous operation, you must not read the decompressed image until the decompressor indicates that the operation is complete by calling your completion function. Set asyncCompletionProc to nil to specify synchronous decompression. If you set asyncCompletionProc to -1, the operation is performed asynchronously but the decompressor does not call your completion function.

SPECIAL CONSIDERATIONS

Only if the asyncCompletionProc parameter of CompressSequenceFrame is not nil are the following conditions in effect: the compressed data must remain valid until the completion function is called with its codecCompletionSource flag, and the pixels in the destination image will not be valid until the completion function is called with its codecCompletionDest flag set.

RESULT CODES

noErr	0	No error
paramErr	-50	Invalid parameter specified
memFullErr	-108	Not enough memory available
noCodecErr	-8961	The Image Compression Manager could not find the specified compressor
codecSpoolErr	-8966	Error loading or unloading data